Skip to content

A tour of the .NET Compiler SDK visualizer - #4579

Merged
BillWagner merged 7 commits into
dotnet:masterfrom
BillWagner:provide-installation-and-prereqs
Mar 27, 2018
Merged

BillWagner merged 7 commits into
dotnet:masterfrom
BillWagner:provide-installation-and-prereqs

Conversation

@BillWagner

@BillWagner BillWagner commented Mar 8, 2018 •

Copy link
Copy Markdown
Member

Fixes dotnet/Roslyn-api-docs#36

Incorporate the content from the Roslyn Wiki for the Syntax Visualizer

Update screenshots, update the text, and add to the .NET Compiler SDK section of docs.

/cc @jinujoseph @mavasani @MaStr11 @gewarren

Internal review link

This commit addes the following:
1. Import syntax visualizer doc from roslyn-wiki: https://github.com/dotnet/roslyn/wiki/Syntax%20Visualizer
2. Add images.
3. provide include for installation instructions.
4. update index and TOC.
The existing text was written when the SDK was in preview mode. All screenshots have been updated. The text was updated for product names, formatted, and reviewed.
@jinujoseph

Copy link
Copy Markdown

cc @sharwell , @jmarolf

@BillWagner BillWagner changed the title [WIP] A tour of the .NET Compiler SDK visualizer A tour of the .NET Compiler SDK visualizer Mar 9, 2018
> The following samples require the **.NET Compiler SDK** installed as part of Visual Studio 2017. You can find the .NET Compiler SDK as the last optional component listed under the **Visual Studio extension development** workload. The templates aren't installed without this component.

You can see the finished code for this sample in [our GitHub repository](https://github.com/dotnet/docs/tree/master/samples/csharp/roslyn-sdk/SemanticQuickStart).
You can see the finished code for this sample in [our GitHub repository](https://github.com/dotnet/samples/csharp/roslyn-sdk/SemanticQuickStart).

@MaStr11 MaStr11 Mar 9, 2018 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


Pause typing once you have typed `Console.`. The tree has some items colored in pink. At this point, there are errors (also referred to as ‘Diagnostics’) in the typed code. These errors are attached to nodes, tokens, and trivia in the syntax tree. The visualizer shows you which items have errors attached to them highlighting the background in pink. You can inspect the errors on any item colored pink by hovering over the item. The visualizer will only display syntactic errors - those errors related to the syntax of the typed code – it will not display any semantic errors.

## Syntax Graphs

@MaStr11 MaStr11 Mar 9, 2018 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this requires the DGML Editor

2018-03-09 18_41_46-visual studio installer

But I'm not sure. I don't have it installed and it doesn't shows the option View Directed Syntax Graph in the context menu.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MaStr11 What version of Visual Studio do you have? I don't see the DGML-Editor in the installer options.

@jinujoseph I'm currently looking at Visual Studio 15.6. Is the DGML Editor now always included?

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's VS Professional 2017 15.6.0. The editor is listed on the Individual components page. I'm not certain if this component is really a/the requirement.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! That was it.

Interestingly, the DGML component does not show up under any workload. You must use the "individual components" tab.

Comment thread docs/csharp/roslyn-sdk/index.md Outdated
- [Work with syntax](work-with-syntax.md)
- [Work with semantics](work-with-semantics.md)
- [Work with a workspace](work-with-workspace.md)
- [Explore code with the syntax visualizer](syntax-visualizer.md)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the syntax visualizer listed twice here?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is still duplicated, @BillWagner.

---
# Explore code with the syntax visualizer

This article provides an overview of the Syntax Visualizer tool that ships as part of the .NET Compiler Platform ("Roslyn") SDK. The Syntax Visualizer is a tool window that helps you inspect and explore syntax trees. It's an essential tool to understand the models for code you want to analyze. It's also a debugging aid when you develop your own applications using the .NET Compiler Platform (“Roslyn”) SDK. Open this tool as you create your first analyzers. The visualizer helps you understand the models used by the APIs.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to mention alternative ways of viewing the syntax tree, like SharpLab or LINQPad?


## Syntax Visualizer

The **Syntax Visualizer** enables inspection of the syntax tree for the C# or VB code file in the current active editor window inside the Visual Studio IDE. The visualizer can be launched by clicking on **View** –> **Other Windows** –> **Syntax Visualizer**. You can also use the **Quick Launch** toolbar in the upper right corner. Type "syntax" and the command to open the **Syntax Visualizer** should appear.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: if you're already using Unicode en dash here, wouldn't it make sense to go the whole way and use Unicode right arrow (U+2192)? It would look like this:

View → Other Windows → Syntax Visualizer

The alternative is of course to use ASCII ->.

(I looked and the only current use of "en dash - greater than" was an error: #4644.)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or if you are typing it, →


As shown in the preceding images, the visualizer tool window displays the syntax tree at the top and a property grid at the bottom. The property grid displays the properties of the item that is currently selected in the tree, including the .NET *Type* and the *Kind* (SyntaxKind) of the item.

Syntax trees comprise three types of items – *nodes*, *tokens*, and *trivia*. You can read more about these types in the [.NET Compiler Platform SDK Overview document](compiler-api-model.md). Items of each type are represented using a different color. Click on the button titled ‘Legend’ for an overview of the colors used.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Overview does not explain what nodes, tokens and trivia are. Did you mean to link to work-with-syntax.md?


The visualizer refreshes the tree to match modifications in the active code file. Add a call to `Console.WriteLine()` inside `Main()`. As you type, the visualizer refreshes the tree.

Pause typing once you have typed `Console.`. The tree has some items colored in pink. At this point, there are errors (also referred to as ‘Diagnostics’) in the typed code. These errors are attached to nodes, tokens, and trivia in the syntax tree. The visualizer shows you which items have errors attached to them highlighting the background in pink. You can inspect the errors on any item colored pink by hovering over the item. The visualizer will only display syntactic errors - those errors related to the syntax of the typed code – it will not display any semantic errors.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: inconsistent use of dashes here: the opening dash is hyphen, the closing dash is en dash.


Semantic inspection operations are only available on nodes. They are not available on tokens or trivia. Not all nodes have interesting semantic information to inspect. When a node doesn't have interesting semantic information, clicking on **View * Symbol (if any)** shows a blank property grid.

You can read more about APIs for performing semantic analysis in the [Work with semantics](work-with-semantics.md) overview documents.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

documents → document


You can read more about APIs for performing semantic analysis in the [Work with semantics](work-with-semantics.md) overview documents.

## Closing and disabling syntax visualizer

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the section called "closing and disabling", if it only explains that you can close the visualizer?

@gewarren gewarren left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left some comments. Also as a general comment about the screenshots, we are supposed to use a thin grey border around screenshots that have white around the edges. Also, we are supposed to use a red box to highlight things within the screenshot. See this.

@@ -0,0 +1,138 @@
---
title: Explore code with the syntax visualizer

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For SEO, something like "explore code with the Roslyn syntax visualizer in Visual Studio".


This article provides an overview of the Syntax Visualizer tool that ships as part of the .NET Compiler Platform ("Roslyn") SDK. The Syntax Visualizer is a tool window that helps you inspect and explore syntax trees. It's an essential tool to understand the models for code you want to analyze. It's also a debugging aid when you develop your own applications using the .NET Compiler Platform (“Roslyn”) SDK. Open this tool as you create your first analyzers. The visualizer helps you understand the models used by the APIs.

[!INCLUDE[interactive-note](~/includes/roslyn-installation.md)]

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These instructions aren't correct. It tells you to choose the 'individual components' tab, but then it tells you to choose a workload. It should either say, choose the extension development workload (from the workloads tab) and then select the .NET complier platform SDK component in the summary pane on the right. Or it should say, choose the .NET compiler platform SDK component on the individual components tab (it's under the "Compilers, build tools, and runtimes" category). Sidenote: one could argue it is actually in the wrong category - perhaps it should be under the last category which is SDKs, libraries, and frameworks.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also updated the include to add the DGML editor, and removed the note about that in this article.


## Syntax Visualizer

The **Syntax Visualizer** enables inspection of the syntax tree for the C# or VB code file in the current active editor window inside the Visual Studio IDE. The visualizer can be launched by clicking on **View** –> **Other Windows** –> **Syntax Visualizer**. You can also use the **Quick Launch** toolbar in the upper right corner. Type "syntax" and the command to open the **Syntax Visualizer** should appear.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are supposed to use the greater than sign (>) for successive menu choices (e.g. View > Other Windows > etc.).


Dock this tool window at a convenient location inside Visual Studio, such as the left side. The Visualizer shows information about the current code file.

Create a new project using the **File** –> **New Project** command. You can create either a VB or C# project. When Visual Studio opens the main code file for this project, the visualizer displays the syntax tree for it. You can open any existing C# / VB file in this Visual Studio instance, and the visualizer displays that file's syntax tree. If you have multiple code files open inside Visual Studio, the visualizer will always display the syntax tree for the currently active code file, the code file that has keyboard focus.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acrolinx will tell you to use the present tense where possible, i.e. "the visualizer displays the syntax tree for..."

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm. I thought I'd run acronlinx on this. Ran it again to find other issues....


Each item in the tree also displays its own **span**. The **span** is the indices of that node in the text file. In the preceding C# example, the selected “UsingKeyword [0..5)” token has a **Span** that is 5 characters wide, [0..5). The "[..)" notation means that the starting index is part of the span, but the ending index is not.

There are two ways two navigate the tree:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

*two ways to navigate


There are two ways two navigate the tree:
* Expand or click on items in the tree. The visualizer automatically selects the text corresponding to this item’s Span in the code editor.
* Clicking or Select text in the code editor. In the preceding VB example, if you select the line containing "Module Module1" in the code editor, the visualizer automatically navigates to the corresponding ModuleStatement node in the tree.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

*Click or select text (i.e. keep tense and capitalization consistent)


The visualizer refreshes the tree to match modifications in the active code file. Add a call to `Console.WriteLine()` inside `Main()`. As you type, the visualizer refreshes the tree.

Pause typing once you have typed `Console.`. The tree has some items colored in pink. At this point, there are errors (also referred to as ‘Diagnostics’) in the typed code. These errors are attached to nodes, tokens, and trivia in the syntax tree. The visualizer shows you which items have errors attached to them highlighting the background in pink. You can inspect the errors on any item colored pink by hovering over the item. The visualizer will only display syntactic errors - those errors related to the syntax of the typed code – it will not display any semantic errors.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

*the visualizer only displays syntactic errors [...] it does not display any semantic errors.

@BillWagner
BillWagner requested a review from mairaw March 23, 2018 21:31
@BillWagner

Copy link
Copy Markdown
Member Author

@mairaw This one is ready to go.

@rpetrusha rpetrusha left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left a number of comments, @BillWagner; you can choose which you want to address. The major comments concern using tabs to segregate C# and VB content. I'd highly recommend doing it, though not until after this PR is merged.

Comment thread docs/csharp/roslyn-sdk/index.md Outdated
- [Work with syntax](work-with-syntax.md)
- [Work with semantics](work-with-semantics.md)
- [Work with a workspace](work-with-workspace.md)
- [Explore code with the syntax visualizer](syntax-visualizer.md)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is still duplicated, @BillWagner.


## Syntax Visualizer

The **Syntax Visualizer** enables inspection of the syntax tree for the C# or VB code file in the current active editor window inside the Visual Studio IDE. The visualizer can be launched by clicking on **View** > **Other Windows** > **Syntax Visualizer**. You can also use the **Quick Launch** toolbar in the upper right corner. Type "syntax" and the command to open the **Syntax Visualizer** should appear.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

comma after syntax


Dock this tool window at a convenient location inside Visual Studio, such as the left side. The Visualizer shows information about the current code file.

Create a new project using the **File** > **New Project** command. You can create either a VB or C# project. When Visual Studio opens the main code file for this project, the visualizer displays the syntax tree for it. You can open any existing C# / VB file in this Visual Studio instance, and the visualizer displays that file's syntax tree. If you have multiple code files open inside Visual Studio, the visualizer displays the syntax tree for the currently active code file, the code file that has keyboard focus.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: "the code file that has keyboard focus" is best in parens.


As shown in the preceding images, the visualizer tool window displays the syntax tree at the top and a property grid at the bottom. The property grid displays the properties of the item that is currently selected in the tree, including the .NET *Type* and the *Kind* (SyntaxKind) of the item.

Syntax trees comprise three types of items – *nodes*, *tokens*, and *trivia*. You can read more about these types in the [Work with syntax](work-with-syntax.md) article. Items of each type are represented using a different color. Click on the button titled ‘Legend’ for an overview of the colors used.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

better: button titled 'Legend' --> Legend button


Create a new project using the **File** > **New Project** command. You can create either a VB or C# project. When Visual Studio opens the main code file for this project, the visualizer displays the syntax tree for it. You can open any existing C# / VB file in this Visual Studio instance, and the visualizer displays that file's syntax tree. If you have multiple code files open inside Visual Studio, the visualizer displays the syntax tree for the currently active code file, the code file that has keyboard focus.

![Visualizing a C# syntax tree](media/visualize-csharp.png)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should you use tabs here?


![A constant value](media/constant-value.png)

The preceding example can also be replicated in VB. Type `Dim x As Double = 1 + 1` in a VB file. Select the expression `1 + 1` in the code editor window. The visualizer highlights the corresponding **AddExpression** node in the visualizer. Repeat the preceding steps for this **AddExpression** and you should see identical results.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With tabs, each could be in its own tab.

End Module
```

This code introduces an alias named `C` that maps to the type `System.Console` at the top of the file and uses this alias inside `Main()`. Select the use of this alias, the `C` in `C.WriteLine()`, inside the method. The visualizer selects the corresponding **IdentifierName** node in the visualizer. Right-click this node and click on **View Symbol (if any)**. The property grid indicates that this identifier is bound to the type `System.Console` as shown in the following figure:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

inside the method --> inside the `Main` method


![AliasSymbol properties](media/alias-symbol.png)

Inspect the symbol corresponding to any declared type, method, property, and more. Select the corresponding node in the visualizer and click on **View Symbol (if any)**. Select the method `Sub Main()`, including the body of the method. Click on **View Symbol (if any)** for the corresponding **SubBlock** node in the visualizer. The property grid shows the **MethodSymbol** for this **SubBlock** has name `Main` with return type `Void`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"and more" seems out of -place. Just a period after property?
Since void isn't a VB term, just in case, explain that Void means no return value


![Viewing symbol for a method declaration](media/method-symbol.png)

The above VB examples can be easily replicated in C#. Type `using C = System.Console;` in place of `Imports C = System.Console` for the alias. The preceding steps in C# yields identical results in the visualizer window.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yields --> yield

Comment thread includes/roslyn-installation.md Outdated

There are two different ways to find the **.NET Compiler Platform SDK** in the **Visual Studio Installer**:

Install using the **Workloads** view:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd do this as level-3 head, and change the "You can also install using..." to "Install using the Individual Components tab" as a level-3 head. Otherwise, the structure of this section seems unclear.

@BillWagner BillWagner added this to the Sprint 133 (3/17/18 - 4/06/18) milestone Mar 27, 2018
@BillWagner BillWagner self-assigned this Mar 27, 2018
@BillWagner
BillWagner merged commit ce425b1 into dotnet:master Mar 27, 2018
1. Select the **Individual components** tab
1. Check the box for **.NET Compiler Platform SDK**. You'll find it last under the **Compilers, build tools ,and runtimes** section.

Optionally, you'll also want the **DGML editor** to display graphs in the visualizer:

@MaStr11 MaStr11 Mar 27, 2018 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for being late but it seems that this is the wrong option

dotnet/roslyn-sdk#65

The issue mentions Code map is the right choice but maybe it's both. I haven't tested either.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MaStr11 Thanks for pointing this out. I did experiments, and only the DGML editor is needed. The Code Map feature depends on the DGML editor, so that will work too.

![Visualizing a VB syntax tree](media/visualize-visual-basic.png)
---

As shown in the preceding images, the visualizer tool window displays the syntax tree at the top and a property grid at the bottom. The property grid displays the properties of the item that is currently selected in the tree, including the .NET *Type* and the *Kind* (SyntaxKind) of the item.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is something broken with the tab. The text starting with "As shown in preceding.." isn't shown if you open the C# tab. It is only visible if you open the VB tab:
visual-basic
csharp

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in PR #4824

@BillWagner
BillWagner deleted the provide-installation-and-prereqs branch March 28, 2018 18:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

8 participants